feat: 근로자 링크 전달 상태 기록·조회 API 구현 - #118

왜 필요한가요?

Closes #117

근로자 보안 링크를 발급한 상태와 HR이 외부 채널로 전달 완료한 상태를 구분해야 합니다. 기존에는 링크가 존재하기만 해도 업무함이 REQUEST_SENT로 표시되어, 아직 보내지 않은 링크도 요청전송으로 보였습니다.

SENT는 문자·카카오톡 사업자의 실제 수신 보장이 아니라 HR이 "전송 완료"를 기록한 상태입니다.

무엇이 바뀌나요?

Worker Link 상태

• 링크 발급 직후 delivery_status=NOT_SENT
• HR이 전달 완료를 기록하면 delivery_status=SENT
• Server 시각의 sent_at과 JWT Actor의 sent_by 저장
• 재발급된 새 링크는 다시 NOT_SENT로 시작
• DB CHECK와 tenant-aware FK로 상태 조합과 사업장 Actor를 검증

API

• GET /api/v1/tasks/{taskId}/worker-link
  • 현재 활성 링크 ID·상태·전달 상태·전달 시각·만료시각 조회
  • 원본 token과 URL은 다시 반환하지 않음
• POST /api/v1/worker-links/{workerLinkId}/sent
  • HR/ADMIN의 수동 전달 완료 기록
  • NOT_SENT → SENT 단방향 전이라 반복 호출해도 기존 sent_at과 감사로그가 유지됨
• 기존 링크 발급 응답에 worker_link_id, delivery_status, sent_at 추가

업무함 표시

• 링크 미발급 또는 NOT_SENT → DOCUMENT_PENDING(서류대기)
• 현재 활성 링크가 SENT이고 응답 없음 → REQUEST_SENT(요청전송)
• 읽지 않은 근로자 응답 있음 → REVIEW_REQUIRED(승인대기)
• 폐기·만료된 과거 링크는 REQUEST_SENT 계산에서 제외

보안·감사

• HR/ADMIN만 조회·변경 가능
• 다른 사업장 리소스는 404, VIEWER 변경은 403
• 전달 완료 최초 기록만 WORKER_LINK_SENT 감사 이벤트 생성
• token 원문은 DB·로그·조회 응답에 추가 노출하지 않음

Migration

• V32__add_worker_link_delivery_status.sql
• feat: OCR 실행 이력 저장과 HR 검토 API 구현 #112 OCR은 충돌 방지를 위해 V33·V34로 조정 완료
• 병합 순서: 이 PR → feat: OCR 실행 이력 저장과 HR 검토 API 구현 #112

검증

• ./gradlew clean test
• PostgreSQL 17 Migration·tenant context·RLS·Import 공존 테스트
• 발급 직후 NOT_SENT, 전달 후 SENT 통합 테스트
• 반복 호출 시 동일 sent_at과 감사로그 1건 검증
• 타 사업장 404·VIEWER 403 검증
• Case의 서류대기·요청전송·폐기 링크 표시 검증
• OpenAPI endpoint 검증

Client 연결 기준

1. 링크 발급 응답의 worker_link_id를 보관합니다.
2. 실제 외부 전달을 마친 뒤 POST /api/v1/worker-links/{workerLinkId}/sent를 호출합니다.
3. 새로고침 후 GET /api/v1/tasks/{taskId}/worker-link 또는 Case Projection의 표시 상태를 사용합니다.